Release 10.1A: OpenEdge Development:
Progress 4GL Reference

ADD-RELATION( ) method

Adds a data-relation object for a pair of parent and child buffers to a dynamic ProDataSet object.

Return type: HANDLE

Applies to: ProDataSet object handle

Syntax

ADD-RELATION ( parent-buffer-handle, child-buffer-handle,   [ pairs-list [ , reposition-mode [, nested ] ] ])

parent-buffer-handle

A handle to the parent buffer in the data-relation object.

child-buffer-handle

A handle to the child buffer in the data-relation object.

pairs-list

An expression that evaluates to a comma-separated list of parent-field, child-field pairs describing the relationship between parent and child buffers in the data-relation object using the following syntax:

parent-field1, child-field1 [, parent-fieldn, child-fieldn ] ...)

The first field in the pair is from the parent buffer, the second field is from the child buffer. When filling the ProDataSet object, Progress retrieves data for the child buffer based on an equality match between all pairs of fields unless the Data-Relation is deactivated or there is an explicit query definition for the data source of the child buffer.

You can define a query for the data source of the child buffer, or supply custom logic in response to FILL events that take over complete responsibility for filling one level of the ProDataSet object. In these cases, the pairs-list is not used.

reposition-mode

The reposition mode of the relation between the parent and child temp-tables. If TRUE, the relation mode is REPOSITION. If FALSE, the relation mode is SELECTION. The default value is FALSE.

When the relation mode is SELECTION, the method fills the child temp-table of the data-relation object with all records related to the current parent. When the relation mode is REPOSITION, the relation is effectively ignored during a FILL, and the child of the relation is treated as if it were a top-level buffer.

When navigating a filled ProDataSet object with a SELECTION relation, related data is filtered as it is browsed. This means the child query of the relation is filtered to make available only children of the current parent, and the query is re-opened each time the parent table is repositioned. When navigating a filled ProDataSet object with a REPOSITION relation, the child table query is always set to match all the rows in the child table, and is not re-opened when the parent changes. Only the buffer for the child is repositioned to the matching child for the current parent.

nested

A LOGICAL expression where TRUE directs Progress to nest child rows of ProDataSet buffers within their parent rows when writing the XML representation of data. This also causes the XML Schema definitions for the related temp-tables to be nested. When FALSE, all child rows are written after all parent rows are written. The default value is FALSE.